home *** CD-ROM | disk | FTP | other *** search
/ Mac Format 1995 June / MacFormat 25.iso / Shareware City / Developers / ICProgKit1.0 / APIs / ICAPI.p < prev    next >
Text File  |  1994-12-03  |  5KB  |  99 lines
  1. unit ICAPI;
  2.  
  3. interface
  4.  
  5.     uses
  6. {$ifc undefined THINK_Pascal}
  7.         Types, Files, 
  8. {$endc}
  9.         ICTypes;
  10.  
  11.     function ICStart (var inst: ICInstance; creator: OSType): ICError;
  12.     (* call at application initialisation *)
  13.  
  14.     function ICStop (inst: ICInstance): ICError;
  15.     (* call at application termination *)
  16.  
  17.     function ICFindConfigFile (inst: ICInstance; count: integer; folders: ICDirSpecArrayPtr): ICError;
  18.     (* count is the number of ICDirSpecs that are valid in folders *)
  19.     (* searches the specified folders first, then backs out to preferences folder *)
  20.     (* don't you worry about how it finds the file (; *)
  21.     (* you can pass nil to folders if count is 0 *)
  22.  
  23.     function ICSpecifyConfigFile (inst: ICInstance; config: FSSpec): ICError;
  24.     (* for use *only* by Internet Configuration application *)
  25.  
  26.     function ICGetSeed (inst: ICInstance; var seed: longint): ICError;
  27.     (* returns current seed for prefs file *)
  28.     (* this seed changes every time a preference is modified *)
  29.     (* poll this to detect preference changes by other applications *)
  30.  
  31.     function ICGetPerm (inst: ICInstance; var perm: ICPerm): ICError;
  32.     (* returns the permissions currently associated with this file *)
  33.     (* mainly used by overriding components, applications normally *)
  34.     (* know what permissions they have *)
  35.     
  36.     function ICBegin (inst: ICInstance; perm: ICPerm): ICError;
  37.     (* start reading/writing the preferences *)
  38.     (* must be balanaced by a ICEnd *)
  39.     (* do not call WaitNextEvent between this pair *)
  40.     (* specify either icReadOnlyPerm or icReadWritePerm *)
  41.     (* note that this may open resource files and leave them open until ICEnd *)
  42.  
  43.     function ICGetPref (inst: ICInstance; key: Str255; var attr: ICAttr; buf: Ptr; var size: longint): ICError;
  44.     (* this routine may be called without a ICBegin/ICEnd pair, in which case *)
  45.     (* it implicitly calls ICBegin(inst, icReadOnlyPerm *)
  46.     (* given a key string, returns the attributes and the (optionally) the data for a preference *)
  47.     (* key must not be the empty string *)
  48.     (* if buf is nil then no data fetched and incoming size is ignored*)
  49.     (* size must be non-negative, is size of allocated space for data at buf *)
  50.     (* attr and size and always set on return *)
  51.     (* size is actual size of data (if key present) *)
  52.     (* attr is pref attributes *)
  53.      (* if icTruncatedErr then everything is valid, except you lost some data, size is size of real data*)
  54.     (* on other errors, attr is ICattr_no_change and size is 0 *)
  55.  
  56.     function ICSetPref (inst: ICInstance; key: Str255; attr: ICAttr; buf: Ptr; size: longint): ICError;
  57.     (* this routine may be called without a ICBegin/ICEnd pair, in which case *)
  58.     (* it implicitly calls ICBegin(inst, icReadWritePerm *)
  59.     (* given a key string, sets the attributes and the data for a preference (either is optional) *)
  60.     (* key must not be the empty string *)
  61.     (* if buf is nil then no data stored and size is ignored, used for setting attr *)
  62.     (* size must be non-negative, is size of the data at buf to store *)
  63.     (* icPermErr if ICBegin was given icReadOnlyPerm *)
  64.     (* icPermErr if current attr is locked, new attr is locked and buf <> nil *)
  65.  
  66.     function ICCountPref (inst: ICInstance; var count: longint): ICError;
  67.     (* count total number of preferences *)
  68.     (* if error then count is 0 *)
  69.  
  70.     function ICGetIndPref (inst: ICInstance; n: longint; var key: Str255): ICError;
  71.     (* return the key of the Nth preference *)
  72.     (* n must be positive *)
  73.     (* icPrefNotFoundErr if n is beyond the last preference *)
  74.  
  75.     function ICDeletePref (inst: ICInstance; key: Str255): ICError;
  76.     (* delete the preference specified by key *)
  77.     (* key must not be the empty string *)
  78.     (* preference specified by key must be present *)
  79.     (* icPrefNotFoundErr if it isn't *)
  80.  
  81.     function ICEnd (inst: ICInstance): ICError;
  82.     (* stop reading/writing the preferences *)
  83.  
  84.     function ICDefaultFileName (inst: ICInstance; var name: Str63): ICError;
  85.     (* return the default file name *)
  86.     (* the component calls this routine to set up the default internet configuration file name*)
  87.     (* this allows this operation to be intercepted by a component that has captured us *)
  88.     (* it currently gets it from the component resource file *)
  89.     (* the glue version is hardwired *)
  90.  
  91.     function ICGetComponentInstance (inst: ICInstance; var component_inst: univ Ptr): ICError;
  92.     (* returns noErr and the component instance that we're talking to, if we're using the component *)
  93.     (* returns an error and nil if we're doing it with glue *)
  94.     (* univ Ptr rather than ComponentInstance so that you don't need Components.p *)
  95.     (* in order to use this file *)
  96.  
  97. implementation
  98. end. (* ICAPI *)
  99.